{literal}
<h2>Annotation</h2>
<br>
Object that contains many:<br>
<b>@orm has|owns many|children|parents $className [inverse $inverse] [itemValidator $itemValidator()] [counter $counter]<br></b>
Object that contains one:<br>
<b>@orm has|owns one|child|parent $className [inverse $inverse]<br></b>
<br>
All these tags meaning is same as in one to one relationship.

<h2> Simple 0ne to many relation </h2>
<h3>Source</h3>
<pre class="code">
&lt;?php
class MyParent extends DomArObject {
	/**
	* @orm owns children MyChild inverse parent 
	*/
	private $children;		
}
			
class MyChild extends DomArObject {				
	/**
	* @orm has parent MyParent inverse children
	*/
	private $parent;			
}
?&gt;
</pre>
<h3>Using</h3>
<pre class="code">
&lt;?php
$parent = new MyParent();
$parent->children[] = new MyChild();
$parent->children[] = new MyChild();
$parent->save();

//Accessing children

$parent = MyParent::load( $id );
foreach( $parent->children as $child ) {
	// do something
}

// access children by some criteria
foreach( $parent->children->query()->where('t.id>10')->limit(5)->orderBy('t.id')->commit() as $child ) {
	// do something
}

//Deleting parent and children
$parent->delete();
?&gt;
</pre>

<h2>Item validator</h2>
<pre class="code">
&lt;?php
class MyClass extends DomArObject {

	/**
	* @orm has children SomeClass inverse someProperty itemValidator myValidator
	*/
	public $children;
	
	public function myValidator( SomeClass $object ) {
		if( $object->name == 'Peter' )
			return 1001; // Peter is not allowed!
		return 0;
	}
	
	public function getValidationErrorMessages() {
		return array(
			'children' => array(
				1001 => 'Peter is not allowed!',
			),
		);
	}

}

$a = new MyClass();
$c1 = new SomeClass('Oliver');
$c2 = new SomeClass('Peter');

$a->children[] = $c1; 
$a->children[] = $c2;

$a->save(); // fails as Peter is not allowed.
echo $a->getLastValidationMessages(); // Peter is not allowed!
?&gt;
</pre>


<h2>Listeners</h2>
<pre class="code">
&lt;?php
class MyClass extends DomArObject {

	/**
	* @orm has children SomeClass inverse someProperty
	* @orm listener afterAdd afterAddChild
	* @orm listener afterRemove afterRemoveChild
	*/
	public $children;
	/**
	* @orm number(11)
	*/
	public $count = 0;
	
	public function afterAddChild( SomeClass $child ) {
		$this->count++;
	}
	
	public function afterRemoveChild( SomeClass $child ) {
		$this->count--;
	}
}

$a = new MyClass();
$c = new SomeChild();
echo $a->count; // echoes 0;

$a->children[] = $c;
echo $a->count; // echoes 1;

$c->delete(); // or
$a->children->remove( $c );
echo $a->count; // echoes 0;
?&gt;
</pre>




<h2>Foreaching children</h2>

If you add new items to list these new items are not automatically saved. They will be saved when you call "save" method to parent.<br>
But when you add new item you might still want to foreach through already saved items and new items. This is possible if you use this syntax:
<pre class="code">
&lt;?php
foreach( $someParent->children as $c );

$list = $someParent->children->toArray();
foreach( $list as $c );
?&gt;
</pre>
For example if you do this you will only loop over objects that are saved into database.
<pre class="code">
&lt;?php
foreach( $someParent->children->query()->commit() as $c );
?&gt;
</pre>

Notice that new elements are always added to the end.<br>
<br>
Here is another more illustrative example about how it works.

<pre class="code">
&lt;?php
$p = new SomeParent();
$c1 = new SomeChild();
$c2 = new SomeChild();
$c3 = new SomeChild();

// add children to parent
$p->children->set( array($c1, $c2) );

// Notice that parent is not saved.
foreach( $p->children as $c)
	echo get_class($c) . '|' . $c->id . ' ';
// Outputs: SomeChild|0 SomeChild|0



// Now lets save parent and added children
$p->save();

// do same thing again and we get same result as expected
foreach( $p->children as $c )
	echo get_class($c) . '|' . $c->id . ' ';
// Outputs: SomeChild|1 SomeChild|2



// Now lets add another child. This child is not saved into database
$p->children[] = $c3;
foreach( $p->children as $c)
	echo get_class($c) . '|' . $c->id . ' ';
// Outputs: SomeChild|1 SomeChild|2 SomeChild|0
// Notice that unsaved child is also added to list.



// This will give only two items - these that are saved.
foreach( $p->children->query() as $c ) 
	echo get_class($c) . '|' . $c->id . ' ';
// Outputs: SomeChild|1 SomeChild|2

?&gt;
</pre>


{/literal}